The KeyTech Windows Service Host 1.0 allows developers to quickly and easily write Windows NT services in Visual Basic. Implement a very simple ActiveX interface to receive service Start, Stop, Pause and Continue events.
The Service Host is an executable (ServiceHost.exe) that hosts an ActiveX DLL or control that implements the IService interface (ServiceInterface.tlb). All you need do to create a Windows service is develop an ActiveX DLL and run Service Host to install the service. Example services are included as well as batch files for installing them.
So, for example, the following code is a very simple service that does nothing!
Implements IService
Private Property Get IService_Pausable() As Boolean
' Don't support pause/continue
End Property
Private Sub IService_OnStart()
' Do whatever is required to start the service
End Property
Private Sub IService_OnStop()
' Do whatever is required to stop the service
End Property
Private Sub IService_OnPause()
' Do whatever is required to pause the service
End Property
Private Sub IService_OnContinue()
' Do whatever is required to continue the service
End Property
Private Sub IService_OnControl(ByVal OpCode As Long)
' Do whatever is required to handle control codes
End Property
Private Sub IService_OnShutdown()
' Do whatever is required to shutdown the service
End Property
Installing the service is as easy as running:
servicehost install name=ServiceEx1
display="Service Example 1" progid=ServiceEx1.ExampleService
For further information, visit us at http://www.keytech.com.au or send email to info@keytech.com.au.
To report bugs or suggest enhancements for future releases send email to support@keytech.com.au.
This document assumes the reader has an understanding of Windows Services and the associated Win32 API. For further details refer to the relevant Microsoft documentation.
For users of previous versions of the Service Host ensure that it is uninstalled before installing the new version.
Copy the Service Host files to a directory and run the install.bat batch file. The installation registers the ServiceInterface type library and example service ActiveX DLLs and installs the example services.
The example service DLLs were built using Visual Basic 6 and therefore require the MSVBVM60 runtime. If you're using a different version of Visual Basic you will have to rebuild the examples to use the appropriate Visual Basic runtime. The Service Host executable and the type library do not use any runtime libraries.
To uninstall, run uninstall.bat.
The Service Host executable hosts an ActiveX DLL implementing the IService interface. It may also be used to install hosted services and uninstall services.
To install a service named ServiceEx1 with a display name of "Service Example 1" and implemented by an ActiveX class with a ProgId of ServiceEx1.ExampleService:
servicehost install name=ServiceEx1 display="Service Example 1" progid=ServiceEx1.ExampleService
To uninstall a service named ServiceEx1:
servicehost uninstall name=ServiceEx1
The image path in the Windows registry for a hosted service must include as a parameter the ProgId:
servicehost progid=ServiceEx1.ExampleService
The correct image path is created automatically if you use Service Host to install the service.
The IService interface is used by the Service Host to communicate with the service ActiveX DLL. The service ActiveX DLL must implement this interface.
The sample code illustrates the use of this interface. For more detailed examples refer to the example code in ServiceEx1 and ServiceEx2.
| Property Pausable As Boolean |
| Sub OnStart() |
| Sub OnStop() |
| Sub OnPause() |
| Sub OnContinue() |
| Sub OnControl(ByVal OpCode As Long) |
| Sub OnShutdown() |
The Pausable property should return True if the service supports pause and continue operations.
The OnStart method is called when the service is in the process of starting. It should initiate the service work and then return promptly.
The OnStop method is called when the service is in the process of stopping. It should terminate the service work and then return promptly.
The OnPause method is called when the service is in the process of pausing. It should suspend the service work and then return promptly. OnPause will never be called if the Pausable property returns False.
The OnPause method is called when the service is in the process of continuing after a pause. It should resume the service work and then return promptly. OnContinue will never be called if the Pausable property returns False.
The OnControl method is called whenever a service specific control is sent. Processing is service specific.
The OnShutdown method is called when the system is in the process of shutting down. It should terminate the service work and then return promptly.
Sample code, developed under Visual Basic 6.0, is included. If you wish to build this code, don't forget to include the ServiceInterface type library ("Key Technology Service Interface Type Library") using the Project | References dialog.
ServiceEx1 demonstrates a very simple service, constructed from an ActiveX DLL, that does nothing.
ServiceEx2 demonstrates a service, constructed from an ActiveX control, that beeps periodically.
ServiceInterface is the source for the IService type library.
ServiceTestHarness is the source to the service test harness.
1. What dependencies are there? What version of the VB runtime do I need?
The Service Host has no dependencies. It is written in C++ and doesn't require the VB runtime or any other runtime.
2. What platforms are supported?
The Service Host may be used under Windows NT 4.0 and Windows 2000.
3. What are the steps for creating a service from scratch?
Make sure the ServiceInterface.tlb type library is registered using regsvr32.
Create an ActiveX DLL or control project and in Project References include "Key Technology Service Interface Type Library".
Include an "Implements IService" statement in your service class and implement the various IService properties and methods.
Build your service DLL or OCX and use servicehost.exe to install the service. Note that the ProgId for your service class is formed from the Visual Basic project name and class name (eg. ServiceEx1.ExampleService).
From the Control Panel Service's applet start the service.
4. How do I debug my service?
The ServiceTestHarness may be used to simulate the starting, stopping and controlling of a service ActiveX DLL. However once running as a proper service the best way to debug it is to write to the event log.
5. How do I write to the event log from my service ActiveX DLL?
Use App.LogEvent to write to the event log. For more sophisticated event logging you may wish to use our Event Logger ActiveX control.
6. How do I start my service?
The simplest way to start a service is to use the Services control panel applet. If the service display name doesn't appear then you need to install the service and try again.
7. Why doesn't my service start?
Typically either the service ActiveX DLL hasn't been registered or it hasn't been installed as a service properly. The Service Host writes any errors to the event log so check the log for further details.
8. I get an error 340 or 499 when I attempt to start my service. What does it mean?
This is a COM error number returned from
Windows. Usually it means the Prog ID of the ActiveX DLL is wrong,
the DLL hasn't been correctly registered, or the DLL is missing.
9. Can I display a message box?
You can but it isn't recommended. Whilst a message box is on display the service cannot respond to stop or any other requests from the Service Control Manager. Also you must ensure the service is configured to interact with the desktop otherwise the service will block but not display the message box.
10. Can I just write all my code in the OnStart method?
No. Visual Basic uses apartment threads. Whilst the OnStart method is executing, any other method calls (eg. OnStop) are queued awaiting execution. The service needs to be responsive so it may be stopped and otherwise controlled.
You must use the OnStart method to initiate, but not perform, the actual service work and once this is done it should return as promptly as possible.
11. Can I abort the service start?
Yes. To abort service start just raise an error, using Err.Raise, from within the OnStart method.
12. Why did my service stop unexpectedly?
The evaluation version of Service Host automatically stops the service after 30 minutes. To confirm that this is what occurred check the event log.
13. I don't want to write a service, I just want to be able to manage them. How can I?
Our Service Manager ActiveX control provides complete Service Control Manager functionality.